COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	%Start Part 2 of 8 functi.tex
C00031 ENDMK
C⊗;
%Start Part 2 of 8 functi.tex
\Defmeth {change-class} {({\it instance\/} standard-object) ({\it new-class\/} standard-class)}

\Defmeth {change-class} {({\it instance\/} t) ({\it new-class\/} symbol)}

\label Arguments:

The {\it instance\/} argument is a Lisp object.

The {\it new-class\/} argument is a class object or a symbol that names
a class. 

If the second of the above methods is selected, that method
invokes {\bf change-class} on {\it instance\/} and {\tt
(find-class {\it new-class\/})}.

\label Values:

The modified instance is returned.  The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.

\label Examples:

\screen!

(defclass position () ())

(defclass x-y-position (position)
    ((x :initform 0 :initarg :x)
     (y :initform 0 :initarg :y)))
\endscreen!
\vfill\eject
\screen!

(defclass rho-theta-position (position)
    ((rho :initform 0)
     (theta :initform 0)))

(defmethod update-instance-for-different-class :before ((old x-y-position) 
                                                        (new rho-theta-position)
                                                        &key)
  ;; Copy the position information from old to new to make new
  ;; be a rho-theta-position at the same position as old.
  (let ((x (slot-value old 'x))
        (y (slot-value old 'y)))
    (setf (slot-value new 'rho) (sqrt (+ (* x x) (* y y)))
          (slot-value new 'theta) (atan y x))))

;;; At this point an instance of the class x-y-position can be
;;; changed to be an instance of the class rho-theta-position using
;;; change-class:

(setq p1 (make-instance 'x-y-position :x 2 :y 0))

(change-class p1 'rho-theta-position)

;;; The result is that the instance bound to p1 is now an instance of
;;; the class rho-theta-position.   The update-instance-for-different-class
;;; method performed the initialization of the rho and theta slots based
;;; on the value of the x and y slots, which were maintained by
;;; the old instance.

\endscreen!

\label Remarks:

After completing all other actions, {\bf change-class} invokes the generic
function {\bf update-instance-for-different-class}.  The generic function
{\bf update-instance-for-different-class}
can be used to assign values to slots in the transformed instance.

The generic function {\bf change-class} has several semantic difficulties.
First, it performs a destructive operation that can be invoked within a
method on an instance that was used to select that method. When multiple
methods are involved because methods are being combined,
the methods currently executing or about to be executed
may no longer be applicable.  Second, some implementations might use compiler
optimizations of slot access, and when the class of an instance is
changed the assumptions the compiler made might be violated.
This implies that a programmer must not use {\bf
change-class} inside a method if any methods for that generic function 
access any slots, or the results are undefined.

\vfill\eject
\label See Also:
 
``Changing the Class of an Instance''

{\bf update-instance-for-different-class}

\endcom





\begincom{class-name, (setf class-name)}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf class-name} takes a class object and returns its
name.

The generic function {\bf (setf class-name)} takes a class object and sets
its name.

\label Syntax:

\Defgen {class-name} {class}

\Defgen {(setf class-name)} {new-value class}

\label Method Signatures:

\Defmeth {class-name} {({\it class\/} class)}

\Defmeth {(setf class-name)} {{\it new-value\/} ({\it class\/} class)}

\label Arguments:

The {\it class\/} argument is a class object.

The {\it new-value\/} argument is any object.

\label Values:

The name of the given class is returned.

\label Remarks:

The name of an anonymous class is {\bf nil}.

If $S$ is a symbol such that $S =${\tt (class-name $C$)} and $C =${\tt
(find-class $S$)}, then $S$ is the proper name of $C$.  For further
discussion, see the section ``Classes.''

\label See Also:

``Classes''

{\bf find-class}

\endcom



\begincom{class-of}\ftype{Function}

\label Purpose:

The function {\bf class-of} returns the class of which
the given object is an instance.

\label Syntax:

\Defun {class-of} {object}

\label Arguments:

The argument to {\bf class-of} may be any Common Lisp object.

\label Values:

The function {\bf class-of} returns the class of which
the argument is an instance.

\endcom


\begincom{compute-applicable-methods}\ftype{Function}

\label Purpose:

Given a generic function and a set of arguments, the function
{\bf compute-applicable-methods} returns the set of methods
that are applicable for those arguments.  The methods are
sorted according to precedence order.  See the section
``Method Selection and Combination.''

\label Syntax:

\Defun {compute-applicable-methods} {generic-function function-arguments}

\label Arguments:

The {\it generic-function\/} argument is a generic function object.
The {\it function-arguments\/} argument is a list of the arguments to
that generic function.

\label Values:

The result is a list of the applicable methods in order of precedence.

\label See Also:

``Method Selection and Combination''

\endcom


\begincom{defclass}\ftype{Macro}

\label Purpose:

The macro {\bf defclass} defines a new named class.  It returns the new class
object as its result.

The syntax of {\bf defclass} provides options for specifying
initialization arguments for slots, for specifying default
initialization values for slots, and for requesting that methods on
specified generic functions be automatically generated for reading and
writing the values of slots.  No reader or writer functions are
defined by default; their generation must be explicitly requested.

Defining a new class also causes a type of the same name to be
defined.  The predicate {\tt (typep {\it object class-name\/})} returns
true if the class of the given object is {\it class-name\/} itself or
a subclass of the class {\it class-name}.  A class object can be used
as a type specifier.  Thus {\tt (typep {\it object class\/})} returns true
if the class of the {\it object\/} is {\it class\/} itself or a
subclass of {\it class}.

\eject
\label Syntax:

\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it class-name} \paren{\star{\curly{superclass-name}}}
\paren{\star{\curly{slot-specifier}}}%
 $\lbrack\!\lbrack\downarrow\!\hbox{{\it class-option}}\,\rbrack\!\rbrack$\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it superclass-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-specifier\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/}  $\lbrack\!\lbrack\downarrow\!\hbox{{\it slot-option}}\,\rbrack\!\rbrack$)\cr
\Vskip 1pc!
\+&{\it slot-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &\star{\curly{{\tt :reader} {\it reader-function-name\/}}} $\vert$ \cr
\+&&\star{\curly{{\tt :writer} {\it writer-function-name\/}}} $\vert$ \cr
\+&&\star{\curly{{\tt :accessor} {\it reader-function-name\/}}} $\vert$ \cr
\+&&\curly{{\tt :allocation} {\it allocation-type\/}} $\vert$ \cr
\+&&\star{\curly{{\tt :initarg} {\it initarg-name\/}}} $\vert$ \cr
\+&&\curly{{\tt :initform} {\it form\/}} $\vert$ \cr
\+&&\curly{{\tt :type} {\it type-specifier\/}} $\vert$ \cr
\+&&\curly{{\tt :documentation} {\it string\/}} \cr
\Vskip 1pc!
\+&{\it reader-function-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it writer-function-name\/}::$=$ {\it function-specifier\/}\cr
\Vskip 1pc!
\+&{\it function-specifier\/}::$=$ \curly{{\it symbol\/} $\vert$ {\tt (setf {\it symbol\/})}}\cr
\Vskip 1pc!
\+&{\it initarg-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :default-initargs} {\it initarg-list\/}) $\vert$ \cr
\+&&({\tt :documentation} {\it string\/}) $\vert$ \cr
\+&&({\tt :metaclass} {\it class-name\/}) \cr
\Vskip 1pc!
\+&{\it initarg-list\/}::$=$ \star{\curly{\it initarg-name default-initial-value-form}} \cr
}
\caption{Syntax for defclass}
\endfig

\vfill\eject


\label Arguments:

The {\it class-name\/} argument is a non-{\bf nil} symbol.  It becomes
the proper name of the new class.  If a class with the same proper
name already exists and that class is an instance of {\bf
standard-class}, and if the {\bf defclass} form for the definition of the
new class specifies a class of class {\bf standard-class}, the definition
of the existing class is replaced.

Each {\it superclass-name\/} argument is a non-{\bf nil} symbol that
specifies a direct superclass of the new class.  The new class will
inherit slots and methods from each of its direct superclasses, from
their direct superclasses, and so on.  See the section ``Inheritance''
for a discussion of how slots and methods are inherited.

Each {\it slot-specifier\/} argument is the name of the slot or a list
consisting of the slot name followed by zero or more slot options.
The {\it slot-name\/} argument is a symbol that is syntactically valid
for use as a Common Lisp variable name.  If there are any duplicate
slot names, an error is signaled.

The following slot options are available:

\beginlist

\item{\bull}
The {\bf :reader} slot option specifies that an unqualified method is
to be defined on the generic function named {\it
reader-function-name\/} to read the value of the given slot.
The {\it reader-function-name\/} argument is a non-{\bf nil}
symbol.  The {\bf :reader} slot option may be specified more than once
for a given slot.

\item{\bull} 
The {\bf :writer} slot option specifies that an unqualified method is
to be defined on the generic function named {\it
writer-function-name\/} to write the value of the slot.  The
{\it writer-function-name\/} argument is a function specifier.
The {\bf :writer} slot option may be specified more than once for a
given slot.

\item{\bull} 
The {\bf :accessor} slot option specifies that an unqualified method
is to be defined on the generic function named {\it
reader-function-name\/} to read the value of the given slot
and that an unqualified method is to be defined on the generic
function named {\tt (setf {\it reader-function-name\/})} to be
used with {\bf setf} to modify the value of the slot.  The {\it
reader-function-name\/} argument is a non-{\bf nil} symbol.
The {\bf :accessor} slot option may be specified more than once for a
given slot.

\item{\bull} 
The {\bf :allocation} slot option is used to specify where storage is
to be allocated for the given slot.  Storage for a slot may be located
in each instance or in the class object itself.  The value of the {\it
allocation-type\/} argument can be either the keyword {\bf :instance}
or the keyword {\bf :class}.  The {\bf :allocation} slot option may be
specified once at most for a given slot.  If the {\bf :allocation}
slot option is not specified, the effect is the same as specifying
{\bf :allocation :instance}.

\itemitem{--}
If {\it allocation-type\/} is {\bf :instance}, a local slot of the given name
is allocated in each instance of the class.  

\itemitem{--}
If {\it allocation-type\/} is {\bf :class}, a shared slot of the given
name is allocated in the class object created by this {\bf defclass}
form.  The value of the slot is shared by all instances of the class.
If a class $C\sub1$ defines such a shared slot, any subclass $C\sub2$ of
$C\sub1$ will share this single slot unless the {\bf defclass} form
for $C\sub2$ specifies a slot of the same name or there is a
superclass of $C\sub2$ that precedes $C\sub1$ in the class precedence
list of $C\sub2$ and that defines a slot of the same name.

\item{\bull} The {\bf :initform} slot option is used to provide a default
initial value form to be used in the initialization of the slot.  The
{\bf :initform} slot option may be specified once at most for a given
slot.  This form is evaluated every time it is used to initialize the
slot.  The lexical
environment in which this form is evaluated is the lexical environment
in which the {\bf defclass} form was evaluated.  Note that the lexical
environment refers both to variables and to functions.  For local
slots, the dynamic environment is the dynamic environment in which
{\bf make-instance} was called; for shared slots, the dynamic
environment is the dynamic environment in which the {\bf defclass}
form was evaluated.  See the section ``Object Creation and
Initialization.''

No implementation is permitted to extend the syntax of {\bf defclass}
to allow {\tt ({\it slot-name form\/})} as an abbreviation for {\tt
({\it slot-name\/} :initform {\it form\/})}.

\item{\bull}
The {\bf :initarg} slot option declares an initialization argument
named {\it initarg-name\/} and specifies that this initialization argument
initializes the given slot.  If the initialization argument has a
value in the call to {\bf initialize-instance}, the value will be
stored into the given slot, and the slot's {\bf :initform} slot option, if
any, is not evaluated.  If none of the initialization arguments
specified for a given slot has a value, the slot is initialized
according to the {\bf :initform} slot option, if specified.  The {\bf
:initarg} slot option can be specified more than once for a given
slot.  The {\it initarg-name\/} argument can be any symbol.

\item{\bull}
The {\bf :type} slot option specifies that the contents of the slot
will always be of the specified data type.  It effectively declares
the result type of the reader generic function when applied to an
object of this class.  The result of attempting to store in a slot a
value that does not satisfy the type of the slot is undefined.  The
{\bf :type} slot option may be specified once at most for a given
slot.  The {\bf :type} slot option is further discussed in the section
``Inheritance of Slots and Slot Options.''

\item{\bull}
The {\bf :documentation} slot option provides a documentation string
for the slot.
\endlist

Each class option is an option that refers to the class as a whole
or to all class slots.  The following class options are available:

\beginlist
\item{\bull}
The {\bf :default-initargs} class option is followed by a list of
alternating initialization argument names and default initial value
forms.  If any of these initialization arguments does not appear in
the initialization argument list supplied to {\bf make-instance}, the
corresponding default initial value form is evaluated, and the
initialization argument name and the form's value are added to the end
of the initialization argument list before the instance is created
(see the section ``Object Creation and Initialization'').  The default
initial value form is evaluated each time it is used.  The lexical
environment in which this form is evaluated is the lexical environment
in which the {\bf defclass} form was evaluated.  The dynamic
environment is the dynamic environment in which {\bf make-instance}
was called.  If an initialization argument name appears more than once
in a {\bf :default-initargs} class option, an error is signaled.  The
{\bf :default-initargs} class option may be specified at most once.


\item{\bull} 
The {\bf :documentation} class option causes a documentation string to be
attached to the class name.  The documentation type for this string is
{\bf type}.  The form {\tt (documentation {\it class-name\/} 'type)}
may be used to retrieve the documentation string.  The {\bf
:documentation} class option may be specified once at most.

\item{\bull}
The {\bf :metaclass} class option is used to specify that instances of the
class being defined are to have a different metaclass than the default
provided by the system (the class {\bf standard-class}).  The {\it
class-name} argument is the name of the desired metaclass.  The {\bf
:metaclass} class option may be specified once at most.

\endlist

\label Values:

The new class object is returned as the result.

\label Remarks:

If a class with the same proper name already exists and that class is
an instance of {\bf standard-class}, and if the {\bf defclass} form for
the definition of the new class specifies a class of class {\bf
standard-class}, the existing class is redefined, and instances of it
(and its subclasses) are updated to the new definition at the time
that they are next accessed.  For details, see ``Redefining Classes.''

Note the following rules of {\bf defclass} for standard classes:

\beginlist

\item{\bull}
It is not required that the superclasses of a class be defined before
the {\bf defclass} form for that class is evaluated.

\item{\bull}
All the superclasses of a class must be defined before 
an instance of the class can be made.

\item{\bull}
A class must be defined before it can be used as a parameter
specializer in a {\bf defmethod} form.

\endlist

The \OS\ may be extended to cover situations where these rules are not
obeyed.

Some slot options are inherited by a class from its superclasses, and
some can be shadowed or altered by providing a local slot description.
No class options except {\bf :default-initargs} are inherited.  For a
detailed description of how slots and slot options are inherited, see
the section ``Inheritance of Slots and Slot Options.''

The options to {\bf defclass} can be extended.  It is required that
all implementations signal an error if they observe a class option or
a slot option that is not implemented locally.

It is valid to specify more than one reader, writer, accessor, or
initialization argument for a slot.  No other slot option may appear
more than once in a single slot description, or an error is
signaled.

If no reader, writer, or accessor is specified for a slot, the slot
can only be accessed by the function {\bf slot-value}.

\vfill\eject
\label See Also:

``Classes''

``Inheritance''

``Redefining Classes''

``Determining the Class Precedence List''

``Object Creation and Initialization''

{\bf slot-value

make-instance

initialize-instance}

\endcom
%End Part 2 of 8 functi.tex